Guidelines¶
What can you put into the documentation ?¶
As a literary genre - most literate programs fall under the “how things work” style. While that is useful for complex algorithms its not useful for normal everyday code. You can assume code literacy while writing for programmers. I believe a history book like approach will be more useful for everyday programs. In future I believe literate documents like this will help in documenting the following and much more with the help of hyperlinks, iframes, images, videos …
User stories
Commits
Design decisions
Inspirations
Bugs
Code History
Conversations
Research, Bookmarks
Stack overflow references
Issues
Build Steps
Tutorials
Executable Snippets
How To’s
Cookbook
User Guides
Architecture Diagrams
and memes
For an existing project you can move the following text files directly into the literate programming
Install / Setup
Readme
Changelog
Acknowledgements
Contact Info, other projects
Test / Platform Coverage
Support
License / Legal
You can move the wiki pages.
Ideas for more chapters
Bookmarks
Inspiration
Similar Work / Credits
Rationale
Research / References / Demos / Presentations / Pitches
Demo Video / User Guide
Errors and Edgecases
Todos
How others can contribute
Current Status
Donations
Blog / Community / Chat
Previous Prototypes
API Docs / Coding Guidelines
Internals
Use cases
Schemas
Examples
Dependencies
Benchmarks
Accessibility
Monetization, Resources, Budgets and Revenue Model
Experiments, Risks, Postmortems and Challenges
Algorithms, Protocols, Interfaces and Patterns
Workflows / Processes
Release cycle planning
Marketing analysis, strategies and possibly live metrics
Responsibility and Contact Information
Maintenance concerns and procedures
Equipment notes and human factors
Trade-offs
Productivity tips and tricks / Advanced users
Chapters for designers,
Styleguides
Design guidelines
Use Cases
Links to assets
For games
Story / Characters / Items / World
Level/environment design
Gameplay
Design Assets / Sounds / Music
For moving the main source code I would recommend going by use-case or by feature. If you source code gets big divide it into modules and change the shell scripts appropriately.
https://web.archive.org/web/20150213050134/http://www.literateprogramming.com/documentation.pdf
https://www.makeareadme.com/
https://github.com/cfpb/open-source-project-template
https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
https://guides.github.com/features/wikis/
Misc Notes on Writing¶
Estimating documentation with code becomes tricky. As a solo activity programming will be most similar to writing novels, while programming as a collective activity might be similar to writing for newspapers with all the entailments of collectivist bureaucracies.
Assuming a programmer reads or writes 5 lines per minute, the upper limit of LOC / Day would be - 60 * 5 * 8 => 2400 and for 1 line per minute - 60 * 1 * 8 => 480. Code is similar to screenplays in its structure. A typical screenplay has ~ 6k lines. Based on the word count, a 16kb total-scripts-size can be a good upper limit for a single programmer.
If the Function point (Avg(lines of code / Function)) is 300, then that means a programmer can code at max 1.5 - 8 features per day. For documentation, you can assume you can write 2-3 pages per day.
https://writing.stackexchange.com/questions/26257/how-many-rewrites-should-a-writer-expect-for-a-novel
https://imsdb.com/scripts/Godfather.html
Drafts¶
By Leslie Rose,
Vomit draft - let it fly baby
Story arc pass - main story subplots - overall structure
MC & supporting character arcs - including character development & embellishment
Grammar/punctuation pass & bad habit pass (adverbs/tense/sentence variety/word choice)
Hard copy read - make corrections
Kindle read - make corrections
Holistic read - make corrections (wearing my audience hat)
Publish