This web site has examples that show the very unprofessional state of NHS Digital’s implementing even simple things like NHS numbers. We focus on programming user interfaces for entering NHS numbers.
NHS Digital has some sample user interfaces, including one for entering NHS numbers.
It’s unhelpful just to criticise, so I wrote a NHS Number user interface: it allows a user to enter an NHS number, and you can click through to it from this page. It wasn’t at all difficult — it took me just over two hours to write the first version, plus a day iterating the design and improving details. It took about two hours to write and review the documentation you can read below.
This interactive documentation you are reading was generated automatically from the NHS number user interface (which you can ), so the code shown here is exactly what is used in that demonstration.
The idea is that documentation and code can be very easily interactively hidden or revealed by clicking. You can control exactly what you want to read without being distracted by lots of detail.
Anything — whether code, comments or HTML — that isn’t relevant to explaining the code is initially hidden, to make the code easier to read and understand. You can then look at and explore exactly what you want to see, and in whatever order you like.
You can click on any hidden code or doccumentation to reveal it or to hide it again, or you can press the open all/close all buttons — — to see (or conceal) everything.
Obviously, the exact structure of the documentation (and its initial state) depends on design choices that the developers made. Basically, the documentation works like this: the developer wrote comments in the usual way in the program, and the automatic documentation tool converted the comments into this easier to read interective form, which you are reading now.
If you like, click to run the NHS number interface, then use your browser to open the source file (you probably need to be in developer mode). You’ll see all this interactive documentation embedded in ordinary comments in the HTML and in the source code — the documented source code works directly without anything special needing to be done.
The end of this web page has a brief technical description of all the features of the documentation tool and how it works. It’s really very simple.
This documentation tool (version 1.1) reads any file in any language. Currently, the documentation tool recognizes strings and comments.
Strings are sequences of characters between matched ", ' or `. As usual, within a string, the string delimiter itself can be escaped with \
Comments are standard C or HTML style comments:
// to the end of the line
<!–– to ––>
/* to */
"http://doi.org" is just a string, even though it contains the comment symbol //
All comments (outside of strings) are converted to blue boxes, or to gray boxes if the comment contains @collapse
A comment may contain keywords:
@title text ↵ — Define the title for the generated documentation. You only require one of these — it defines the HTML <title> text for the generated documentation.
Where ↵ means a newline or the end of the comment.
@collapse text ↵ — everything to the next comment containing a matching @end-collapse is collapsed. You can nest collapsed text.
You can have comment text before or after these @collapse and @end-collapse directives, and even more than one directive in one comment if you wish. (It’s often neater to have several @end-collapse directives in a single comment.) Any text between the directives is, of course, treated like comment.
@buttons — the open all/close all buttons are inserted, like this:
(@buttons was used in this comment to show how it works).
@move-up — move this comment to before the preceding code in the generated documentation.
This strange feature is required because HTML files must always start <!DOCTYPE html> ... specifying language and character sets, etc. HTML files cannot start with comment, but when a HTML file is documented, you may want the essential code moved below your own introduction (which needs to be written in a comment), for instance to give the document a title. Code moved after a comment can also be collapsed and hidden if the comment contains a @collapse.
@move-down — conversely, files may need to end with special code, so this allows the documentation to end with arbitrary comment. Since everybody ignores what comes after </html> I haven’t thought of a good use for this yet, but it is an obvious match for @move-up!
@documentation — insert this documentation text.
The @documentation feature might seem quirky, but originally I wrote the explanation of how the tool works in code I was documenting with the tool (so it looked like the explanation you are reading right now). But of course, I also needed the same documentation for the tool itself!
To avoid having two independent descriptions of how the tool works to keep synchronized, I put all the documentation inside the tool, where it properly belongs.
Now that this documentation text is inside the tool, by using @documentation the one-and-only-documentation can be repeated anywhere it’s needed. I can now have lots of independent copies of this documentation text, but I’ve only got to maintain one of them, and all the uses of the documentation are kept up to date automatically every time the tool is run.
Now the documentation is inside the code that implements it, which is the best place for it to be — if I edit the documentation to make it better, I can easily improve the adjacent code to implement the new documentation; conversely, if I modify the code, I can very easily keep its documentation up to date.
@instructions — inserts brief instructions for using the interactive documentation generated by the tool.
The @instructions feature is provided in case the documentation tool is modified and introduces new or different interactive features. Like @documentation (described above), making @instructions a documentation tool function keeps all the information about using the documentation generated by the tool in one place so it’s easier to maintain and keep correct.
@tabs n ↵ — Set the tab size to n instead of the default 8. (Conventionally tabs align to the next multiple of 8 columns, but some code editors let you change it.) You can set tabs at most once in a document.
All the formatting is done using CSS, and the interactivity is done by JavaScript. You can edit both to get different effects.
Finally, because the open/close outlining is interactive, I decided that there is no feature to hide code from sight. You can’t cheat.
That’s it.
Documentation tool used version 1.1Documentation generated at 10:59 pm, 11 October 2022