docfx
docfx copied to clipboard
dotnet
Discussion: Improve the documentation ...
I've been using docfx for a week now, and I cannot stress enough how wonderful it is on one hand, and how confusing and neglectful the documentation is on the other side. In particular when it comes to getting started.
Admittedly, I didn't have the leisure time to spend hours on setting up a doc project, but I'd say that's quite often the case since there's always something more urgent than documentation, right?
Personally, I just wanted the doc project to be set up within an hour or less, ideally, in order to get on working with code. In the end I spent a full two days filled with frustration until I've had docfx working reliably in my project.
Case in point, and last straw that made me blow up internally, is this fragment:
I can overlook the blatant grammar errors. That's like reading code that's not in your preferred code style but at least it's consistent.
But what I cannot overlook is that the documentation continues to RAISE MORE QUESTIONS than it answers, like "What goal are we setting here?" and "Why are we setting 'a goal' here?" and "What's the difference in output?" and most importantly: "Why am I being told about this to begin with??"
That entire paragraph is nothing but a waste of space and worse: waste of user's time!
And this goes on with several of the topics that I've read so far, but most importantly the getting started parts were confusing, to say the least (and I've been programming for ~25 years now!).
Crucial information is hidden throughout the lenghty walkthroughs, interspersed with more information you really don't need when getting started, just to make it even more confusing.
Take, for instance, the simple fact that one doesn't have to put the source code in the src folder but you can actually specify "../../" as path to your sources when docfx is a subfolder of your project. It's a well known thing many users seem to run into and why? Because it's only mentioned "on the side" half-way through the second getting started walkthrough, almost as if that were an optional thing only few users would ever run into, and I quote:
"Also, note that if your csproj files are located outside of your docfx directory, you need to use the src property with ../ to find them:"
Who in their right mind would put their source code in a subfolder of the docfx project?
Right, I know exactly ONE project that works that way ...
I understand that's the way docfx is set up, and it's convenient for the docfx developers to document docfx the way docfx uses docfx to generate its docfx docs.
But that's NOT how users intend to use docfx!
And that's what should be assumed in the documentation: the viewpoint of the average developer looking for a doc generator for one's own project! Docfx is an add-on to existing projects and as such it should be documented how to use it to achieve that goal. That's the common use-case that needs documentation, period! Forget about instructing users how to build the docfx docs, that's ENTIRELY IRRELEVANT!
To give you an example, what I'd really love to see in a getting started document is something like this that's guaranteed to work for practically every user across all platforms and projects:
Install docfx ... (inline instructions here, most simple way)
Open command prompt and navigate to the folder where "docfx" executable resides.
Run this once to setup the docfx project folder structure:
docfx init
Edit the docfx.json file and locate the "metadata/src/src" part, edit it to point to the root folder of your project where the project's .csproj files are, for example if your project resides in "MyProject/MyCode" and docfx is in a subfolder "MyProject/Docs" then use:
"src": "../MyCode"
Run this every time the API (code) changed:
docfx metadata
Run this to build the combined HTML documentation from markdown articles and API metadata (if you only edit markdown you don't need to update metadata):
docfx build
Run this to host the generated HTML docs locally:
docfx --serve
To view the docs, leave the command prompt open from the last command and enter the following in the browser's address bar:
localhost:8080
Refer to .... to learn more about ... .
This is the kind of documentation I WISH had been there from the beginning!
Notice how NONE of the super extra infos you don't need when getting started isn't interspersed here, like changing ports or filtering out APIs - why that article is listed BEFORE the getting started articles is another issue.
Getting started docs also mention optional command line options like -q ... I mean, seriously, if you have to specify a non-essential parameter like -q in the getting started because you're worried (or whatever) that the message spamming will deter users (or whatever), then this should be the default setting and anyone how would rather see all these messages should be the one to specify a command line option like, say, -l instead (that stands for "--LOUD" obviously). :)
I actually wasted two separate days just to get the basics working, and in the meantime I even went back to doxygen and seriously considered purchasing a commercial doc generator. It's only that I don't give up easily that I gave docfx another chance, despite the fact that the documentation rubbed me the wrong way.
Another example: filtering. So that article instructs you to create a filter.txt, specify it in docfx.json, and use something like this: ´´´
- include: uidRegex: ^Microsoft.DevDiv.SpecialCase
- exclude: uidRegex: ^Microsoft.DevDiv ´´´
Didn't work for me. It seemed simple enough but it had no effect. If there were any error messages they got lost in the tons of log spam that occurs every time I run docfx.
Turns out that the file has to begin with ´´´apiRules:´´´ in the first line! The article briefly mentions it OUT OF CONTEXT in the "Format of filter configuration file" and is only included in a lengthy example way down the article. Instead I mistook the initial example (reproduced above) as the simple-most COMPLETE AND WORKING example because that's what you'd expect when you read an article about the "format of filter configuration file".
That was another one or two wasted hours down the drain because the doc is more confusing then helpful. :(
Side note: that docfx.json metadata section contains an array named "src" that contains a string variable named "src". There's obviously something wrong with that! That second "src" should really be named "projectRootFolder" or "relativePathToCsprojFiles" or something else that's similarly descriptive. Everything else in that json has descriptive, self-understood identifiers, except for the one that practically every developer needs to change! That's named "src" under "src". Ouch. :(
I find it particually frustrating when a tool, that's said to help you with one particular thing, doesn't showcase how to do that very thing really well! In case of docfx that would be the documentation. And to top it off, knowing that this is a Microsoft tool makes it all the weirder, seeing how well written MS docs usually are.
I'm sorry if this sounds harsh but I really wanted to rattle the cage here instead of being yet another user that got to learn the ropes of docfx eventually but all the pain goes associated with it is lost to the team who can make the necessary changes to improve the user experience.
If I weren't so deeply involved in my own projects, I'd simply spend a week rehashing the "getting started" docs myself and send a pull request. The least I can do is to spend an hour complaining about that which is obvious because I care about user experiences (especially when mine was painful but the result is great).
Case in point, and last straw that made me blow up internally, is this fragment:
Hmmm, for the highlight.js - Supported Languages both are valid language definitions.
Thank you CodeSmile, these are all great feedbacks and I share the same feeling. There are so many areas to improve for a project whose whole purpose is to create documentation. I took some time to rework some of the docs to be more customer facing and hopefully it'll make it easier for people to understand and follow along.
There are much more improvements needed and we need the community's help to make the documentation better, so I'm converting this issue into a discussion for the community to collaboratively discuss and improve the product docs.
