My Project Documentation Conventions

I have lots of projects on the go at any given time. Most of these have corresponding GitHub repositories. Even though usually I’m the only person working on them, Git is great for version control and GitHub offers very convenient offsite backup and world-facing presence for the material (were I starting from today, GitHub might not be my first choice, I am a little wary of anything Microsoft, but it’s free and I started ages ago).

Most of these things have come about in an ad hoc fashion, so there’s quite a lot of inconsistency. But now I think I should adopt some little standards for myself. An overarching one is to write using Markdown. This I find a pretty optimal compromise between plain text and formatted material. There are loads of tools available, it’s trivial to convert into HTML (built in with GitHub) or say PDF.

An even stronger convention I aim for is no dead links (404). Not always easy in practice, especially given domain name registration, but wherever possible, do it. A URL is for life, not just for xmas. (I do soon have to sort out something close as a fallback, with the aid of purl.org/archive.org).

I have also drifted towards repeating the same pattern when it comes to filenames and directory structure.

So starting at the project git root directory :

• README.md – project ‘Front Page’, featuring overview, summarized status, links to other important parts
• devlog.md – fine-grained status updates, reverse-chronological
• links.md – the most important related links
• src/ – code
• docs/ – more complete documentation
• references/ – a local dump of related documents found online, with topic-specific subdirectories if appropriate (with an index, if/when I get around to it)
• images/ – pictures needed within the documentation
  

I think this lot will work as a reasonable baseline. Parallel to this (as & when I can be bothered), HTML and other formats. Conneg would be the neatest way to deliver, but for pragmatic reasons hypertext links are probably more significant.

With HTML, I tend to use :

• css/ – all CSS
• js/ – all Javascript (personally I prefer to use local files for libraries such as jQuery rather than CDNs, minor performance hit seems better than potential breakage due to external forces)
• images/ – all embedded images

I’ve not yet had the need/desire to do any kind of release, everything being an indefinite incremental work-in-progress. I may well do this for Chatterbox some time soon – there the whole codebase needs tidying up and I’m approaching the point of a (sort-of) finished v. 1.0.0 milestone. As and when I do this, I’ll just follow GitHub conventions.

On that topic, although I’ve been lax on this in the past, the Semantic Versioning conventions make a lot of sense.

If you have any suggestions, please let me know. By the very nature of this kind of thing, it’s only after getting things wrong you realise what you should be doing.