Writing docs

With COVID-19 raging across our planet, sales for Project Wallace have pretty much dried up. Hardly any new paying customers are showing up. And I get that. These are incredibly challenging times. This is probably not the time to make (even a tiny) investment in a tool like Wallace, that you don’t strictly need anyway. This is why I have decided to move my attention to serving the developer community with writing documentation for all Project Wallace’s CSS metrics.

On writing docs

There are so many different metrics in Project Wallace and there’s no good explanation for any of them to be found. This needs to change. To do that, I have created a /docs folder and copied every existing CSS metric and created a Markdown file for it. From here I have started writing documentation. For at least 130 Markdown files.

Writing documentation that someone might actually want to read

Truth be told, I think the progress is pretty slow. I’ve been looking at many websites to figure out what makes documentation pages right. Websites like Mozilla Developer Network and TailwindCSS make it look easy, but look at the details that go into these pages. Here’s a small list of things that I think they do a great job of documenting:

• Code and usage examples.
• Versioning. It’s so useful to have a browser compatibility table or a note about some thing being deprecated or removed.
• Short paragraphs of explanations. No-one wants to plough through a pile of unreadable text.
• Beautiful design. These docs are pleasant to the eye.
• Linkable sub-headings. Don’t underestimate the power of being able to link to a heading far below the fold of a page. I love it when a heading is clickable and gives me the url of that exact heading so I can easily share it.
• Links to related content. It can be useful sometimes to read more about a certain topic on the same or a different website.
• A link to edit the given page directly on GitHub. This is what makes open source great, I think. There is no easier way to get started in OSS than to write or change some documentation.

Certainly I’m going to take a couple of these goodies and apply them to Wallace’s documentation pages!

The way forward

This is where I just need to put in the effort and write all the pages. It’s quite the task I’ve set out for myself, but it helps to have a big chunky checklist in Basecamp and seeing a little progress almost every day. I’ll get there. Eventually.