24th
Docupeopletation
Writing documentation is spectacularly difficult. At least for me. While I’m capable of being quite verbose (perhaps too verbose) in response to a question (perceived or actual) I’m crap at predicting what people will want or need before they get to the point of asking questions.
This is having an unfortunate effect in the land of TiddlyWeb: documentation is lagging quite far behind the functionality of the tool and while I’m generating new documentation on a fairly regular basis I have no way of knowing if it is the right documentation.
Any software project, especially one which is both an application, a library and an HTTP API, has several different types of documentation. There’s the documentation in the code explaining functions, classes, methods, modules and such. With Python there are tools like pylint and pep8.py which will tell you when your code is missing docstrings so TiddlyWeb has most of that covered with at least basic documentation on stuff that is public.
More complicated is the narrative that explains what TiddlyWeb can do and the documentation that explains how to do it. Making it go, getting the best out of it. That’s the stuff that’s hard to do alone; since narrative is a story it only emerges through human communication: feedback loops, a dialog of participants.
