search

lpereira / lwan

Experimental, scalable, high performance HTTP server
https://lwan.ws
GNU General Public License v2.0
5.92k stars 549 forks source link

Documentation for API #139

Open HalosGhost opened 8 years ago

HalosGhost commented 8 years ago

Since lwan is now more and more functional as a library rather than a standalone thing, it would be great to have some solid documentation (like manpages! :D) for the API.

lpereira commented 8 years ago

Documentation is indeed important. I thought about it a few times but never got around actually writing it. If I had some help, specially from a native speaker, it would be great: my portuguenglish isn't the easiest to understand sometimes.

However, being a web server project, I'd pretty much have something different than man pages (which are not the most pleasant thing to write). Something like Gitbook or ReadTheDocs. These can embed diagrams, have hyperlinks, and can have syntax-highlighted code examples.

HalosGhost commented 8 years ago

Why not do both? :smiley:

Documenting the API/library for use with C is something that should definitely have man pages. It's the standard, and deeply appreciated by those of us who spend a lot of time on the CLi.

I would be more than happy to translate any web-based documentation over to man pages and I would be willing to copy-edit for grammar and the like for english docs. But first I need some inkling of how the system works, haha.

lpereira commented 8 years ago

Well, you always have elinks :)

The documentation could be a .txt file and still be quite good. I don't really care what's used to typeset it, as long as the contents are not some auto-generated garbage that doesn't help you get from A to B.

Writing good documentation is hard: it takes a lot of time, patience, and attention to detail. Since Lwan is a side project, and I'm working on other things on my free time, I'm finding it increasingly difficult to carve some quality time for it.

I'm always happy to answer questions about the project, though.

lpereira commented 8 years ago

Marking this as a duplicate of #82.