# About the documentation format



## jronald (Sep 16, 2013)

FreeBSD API documents are like articles, and Microsoft's API document, i.e. MSDN, is more structural. I have used MSDN for a decade, among which used man pages as needed, my conclusion is that MSDN is more convenient than man pages absolutely. Why can not FreeBSD be better here?


----------



## ShelLuser (Sep 16, 2013)

Simple: you don't use MSDN documents on the console ("DOS prompt") which is actually common for manual pages. Different operating systems, different approaches.


----------



## jronald (Sep 17, 2013)

ShelLuser said:
			
		

> Simple: you don't use MSDN documents on the console ("DOS prompt") which is actually common for manual pages. Different operating systems, different approaches.



I should say a structural form is better, and plain text is enough, because a good function should be self explained, and the user of the function should be more likely to check a part of the document of the function. Of course a whole one contains more information, information about every parameter, information about the relationship of the parameters, but when considering what the user demands, the extra information is irrelevant.

*nix style:


> DESCRIPTION
> The function fread reads nmemb elements of data, each size bytes long, from the stream pointed to by stream, storing them at the location given by ptr.
> The function fwrite writes nmemb elements of data, each size bytes long, to the stream pointed to by stream, obtaining them from the location given by ptr.
> 
> ...


MSDN style:


> Parameters
> --------------------------------------------------------------------------------
> buffer
> Storage location for data.
> ...


----------



## drhowarddrfine (Sep 18, 2013)

MSDN is written for web pages. man pages are written for text. They need to fit on one machine installation and not take up a ton of space, which MSDN does. I don't understand why you didn't include the top half of the man page but the same synopsis of the parameters is included in the description. Plus, if you are just trying to look up the argument list, the man page has it at the top while the MSDN page doesn't show it at all in your example. 

As a developer, I used to find MSDN quite verbose and frustrating to go through while the man pages are quick, well-written, and to the point.


----------



## jronald (Sep 18, 2013)

drhowarddrfine said:
			
		

> MSDN is written for web pages. man pages are written for text. They need to fit on one machine installation and not take up a ton of space, which MSDN does. I don't understand why you didn't include the top half of the man page but the same synopsis of the parameters is included in the description. Plus, if you are just trying to look up the argument list, the man page has it at the top while the MSDN page doesn't show it at all in your example.
> 
> As a developer, I used to find MSDN quite verbose and frustrating to go through while the man pages are quick, well-written, and to the point.


Yes, MSDN is in HTML, it is a plus, only plain text will make differences when considering whether the format is structural or not.

I haven't included the top half, because I copied them from the http://www.linuxmanpages.com and MSDN, and they are in HTML, copying HTML as plain text may need some editing, and I think what omitted is only the function prototype, which is not important here.


----------



## kpedersen (Sep 18, 2013)

It wont be long before Microsoft changes their MSDN again to make it more trendy. Manpages have remained the same throughout.

Who remembers this and this? I was actually looking for some VB6 stuff but that isn't even available anymore. Nice one Microsoft. Great docs!

Frankly I prefer consistency over simplicity.

I imagine MSDN also doesn't handle duplicate names very well. Whereas the traditional UNIX way of doing things splits things up into kernel, userland etc... (i.e fork(2), system(3)).


----------



## jronald (Sep 19, 2013)

kpedersen said:
			
		

> It wont be long before Microsoft changes their MSDN again to make it more trendy. Manpages have remained the same throughout.
> 
> Who remembers this and this? I was actually looking for some VB6 stuff but that isn't even available anymore. Nice one Microsoft. Great docs!
> 
> ...



Now Microsoft almost monopolizes the desktop market, and is bureaucratic, not professional enough. But at the beginning, it was professional, for example, when deciding the format of the documents, etc.

Consistency is of course appreciated, but a chaos block of text is always consistent to another, because the condition of consistency is only that each is a block of text.


----------



## ShelLuser (Sep 19, 2013)

Oh, I agree with @kpedersen up there (you knew? What the heck gave that away? ).

I want to add insult to injury; even though I am actually a fan of Microsoft Windows 7, Microsoft Office 2010 and in a love/hate relationship with Visual Studio 2012. I'm not saying, there is enough in my post history.

The only motivation for this being my agitated state, me getting agitated again when being reminded that Microsoft is going to do away with TechNet and I guess I like the thread.

Before we go "Visual Basic 6 is ancient, no one uses that" a few questions come to mind. If Visual Basic 6 is so old that no one uses it any longer, then surely MS DOS is long gone by now?  Errr.. Nope!.

Each to his own, but that strikes me as hypocrite. Strong words, easily said. Sure.

So how come that a MSDN blog is talking about Visual Basic 6 on Windows 8. Could it be people are more interested in MS DOS 6 th_a_n they are in Visual Basic 6?

I don't have facts to back this up, but for some reason I sincerely doubt this one.

My addition to the tread (apart from blowing off some steam): Before anyone goes "sure VB6 is old it had to go, that's the way thing go" reflect on this. There is _nothing_ logical about their takes here and I'm under the impression I shared enough to back up that statement.

(Edit):

Rereading the whole thing, including my rant, we're slacking off (I'm just as much to blame, probably even more).

Documentation: HTML vs Text (correct me if I'm wrong, even then we'll get this back on track).

I don't agree. HTML, HyperText Markup Language. What is there to Mark Up on a text screen? Perhaps better put differently: what is there to mark up which common tools can't do?

Honestly; I don't care for processors which have to shift through all the HTML overhead merely to give me the look and feel I came to love and appreciate. Give me the speed of text and then I'll use that as I see fit.

Which isn't even touching subjects such as locate or apropos.

I don't think markup belongs here.


----------



## drhowarddrfine (Sep 19, 2013)

jronald said:
			
		

> Yes, MSDN is in HTML, it is a plus, only plain text will make differences when considering whether the format is structural or not.
> 
> ...copying HTML as plain text may need some editing


And now you spotted one of the first cracks. Remember, any HTML document is going to require a special viewer to read it and present it properly. It will also be a significantly larger file size. It also needs more time to be updated and made to work in all browsers and I'm sure someone will complain about accessibility. Now multiply that times several hundred files.


----------



## kpa (Sep 19, 2013)

Not to mention HTML is all about presentation, not structure. There's not much you can do with an HTML document to convert it to another format if needed. A documentation format that enforces a structure is a much better choice if conversions to other formats are needed.


----------



## jronald (Sep 19, 2013)

I mean even with only plain text, there is a difference: describe each parameter respectively or describe all the parameters in one block of text. And my opinion is that the former is better.


----------



## kpedersen (Sep 19, 2013)

I see what you mean by separating it out into individual parameters rather than a paragraph containing them all. I can see some advantages to this.

Perhaps this stems from the fact that man pages are not generated from automatic documentation schemes such as Javadoc, Doxygen or Sandcastle / whatever MSDN uses.

Personally, in code I would much prefer a paragraph describing the function in general rather than some XML stuff duplicating the majority of the function signature. If this means that the generated documents cannot appear in the man pages, then I won*'*t lose sleep over it.


----------



## jronald (Sep 20, 2013)

kpedersen said:
			
		

> I see what you mean by separating it out into individual parameters rather than a paragraph containing them all. I can see some advantages to this.
> 
> Perhaps this stems from the fact that man pages are not generated from automatic documentation schemes such as Javadoc, Doxygen or Sandcastle / whatever MSDN uses.
> 
> Personally, in code I would much prefer a paragraph describing the function in general rather than some XML stuff duplicating the majority of the function signature. If this means that the generated documents cannot appear in the man pages, then I won*'*t lose sleep over it.



Generating documents automatically brings something not intuitive in the code, but things can be easier, just add comments in the code, without tags for auto generating document, there are some advantages:


 comment as little as possible, because it is better to let code be self-explanatory, essentially making a function be self-explanatory, BTW the ultimate function is main();
 comment and code become more cohesive, practically they can be managed by a revision control system
 when coding you can check the comment in the editor
 you can comment the usage of a function in the head file, and the implementation detail in the implementation file
 so the document or comments can evolve in an easier way, and so can the code, for example, if things become confusing (firstly the function is not self explained, secondly so does its comment), the code viewer will think, then he/she may understand something, if it is not his/her own problem, he/she is more likely to improve the document, even the code. A dilemma is that something is proved not good enough, and why is it allowed to be checked in?

So an open mind is important. Does FreeBSD get this?


----------



## freethread (Sep 20, 2013)

@jronald, look at /usr/src/Makefile, you can run it with the doxygen parameter


```
# doxygen             - Build API documentation of the kernel, needs doxygen.
```
 
It generates HTML FreeBSD kernel documentation.


----------

