loading...
Cover image for A user story for my markdown parser (MDL Log #2)

A user story for my markdown parser (MDL Log #2)

mortoray profile image edA‑qa mort‑ora‑y ・3 min read

MDL Log (6 Part Series)

1) Time to build a markdown parser and processor (MDL Log #1) 2) A user story for my markdown parser (MDL Log #2) 3 ... 4 3) A comment feature for author markings (MDL Log #3) 4) Parsing footnotes and code blocks (MDL Log #4) 5) Lists and backtick parsing (MDL Log #5) 6) Nested lists and continued paragraph support in MDL

It's time to create the first user story. It's important to understand why I'm doing the parser and what features will be needed. I'll present these user stories are people other than myself since it would sound weird to talk about myself as a user. Plus, it'll help me include the desires of other people. Ultimately the tool isn't just for me, though I am the original market.

User: Keziah

Woman writing on a computer

This is Keziah, she's 32 years old and lives in a big city. She works as a writer for a software development company. Her work ranges from user documentation to case studies, to client pitches. She works closely with the programming team, as well as business development.

Though all of her articles share a similar text-heavy format, she ends up using a different tool for each target. Having to jump around is getting in the way of her work, which is beginning to annoy her. She wants a simplified workflow -- one where all the common work is done with the same tool.

If you'd like to learn more about understanding users, follow me on Skillshare. I'll have a class, "Writing the Perfect User Story" out by the end of the month.

Now that we know a bit about Keziah, what type of feature might appeal to her? Let's phrase something in her domain:

"A user, will format a document in MDL, because they wish to publish in multiple places."

Where MDL is the document format in this project. Does this user story make sense for Keziah? We are assuming, based on her technical experience, that a text-based document format will be accessible to her. Had she be only used Word, this assumption might be invalid.

Publishing in multiple places is something we think will simplify her workflow, a desire she has. It makes sense to go into detail a bit more here. She's not looking to publish in all places, but specific ones. What might those be: let's say they are an eBook format, PDFs, markdown in forums, and HTML for some docs.

This user portrait and the first story gives the impetus for my project. I need to create this common MDL format. A lot of the features cannot be phrased as user stories, but it's nonetheless valuable to keep the users in mind. I don't want to get side-tracked with highly technical features that aren't providing end-user value. I want to focus on features that provide immediate value -- making the product usable early.

Parser Update

I've not had nearly as much time for the project as I had hoped. But I felt like I need a good first step before publishing this update. And I think I have it.

This article was processed by the parser*. It read the markdown and formatted it back to markdown. Well, technically it read MDL, but most of the syntax is the same as Markdown right now. The one difference to see is in the blurb at the end of the article. I use only @Blurb in the source text, and that gets translated into the horizontal rule and italicized section.

*The inclusion of the image, and production of front-matter is not yet withint the capabilities of the processor. They were added by hand after export.

The code is still a mess, and this is typical for a tool at this stage. I'm working on a proof-of-concept, and partially the minimal-viable-product. I do not wish to build the extensibility features until I understand how the whole system will work. I don't believe that architectures can be designed in advance -- instead, I think evolution produces far more usable results.


This is a development log entry for the MDL Document Processor Project.

MDL Log (6 Part Series)

1) Time to build a markdown parser and processor (MDL Log #1) 2) A user story for my markdown parser (MDL Log #2) 3 ... 4 3) A comment feature for author markings (MDL Log #3) 4) Parsing footnotes and code blocks (MDL Log #4) 5) Lists and backtick parsing (MDL Log #5) 6) Nested lists and continued paragraph support in MDL

Posted on Mar 14 '19 by:

mortoray profile

edA‑qa mort‑ora‑y

@mortoray

I'm a creative writer and adventurous programmer. I cook monsters.

Discussion

markdown guide