I have some suggestions and want to work on mitmproxy’s documentation. I wanted to throw my thoughts out to the community so that I could gather some feedback and ideas before doing a bunch of work and dropping in with some PRs. This is a great project, but I feel like it needs better docs! If it would be better I can get these split out into different issues, so that they can be discussed and worked on separately separately.

1. Spruce up the installation instructions.

The Ubuntu instructions need to be fleshed out a bit as I think there are steps missing that even a technical person might not think are obvious. Been a while since I used OS X, and even when I did use it, I’m not familiar with how python works on it(homebrew vs. XCode). Perhaps we could have a pros and cons of why you would install from homebrew vs use the python that comes with XCode. I assume it boils down to a “Do you mind old python vs more setup” thing. I may need some help from someone more familiar with mitmproxy on OS X on this one. Or perhaps make the decision to document one of the methods say, homebrew over XCode.

2. Developer docs

Related to this but somewhat separate I think we should also create developer installation docs so that people know how to get set up to help contribute. Explain what Countershape is and how to write documentation.

3. Command line options in one place

I think we need to have a page that lists all of the command line options for each tool rather than having them scattered throughout the features/examples. I’m aware that you could make the argument “just specify --help at the command line”. The purpose of the command line options page would give someone who hasn’t even installed mitmproxy yet a one-pager on what you can do with mitmproxy, I know this because it was the first page I looked for when I found mitmproxy. I think that it is important that this page be short and sweet and to the point, perhaps linking to related examples.

4. Introduction docs

I would like to hear some feedback on how people feel about the “How mitmproxy works” page vs the “Modes of Operation” page, I feel like this is probably amongst the most polished documentation within this project, but perhaps there is a bit of duplication between the two pages. Maybe we can re-work these two pages by splitting each of mitmproxy’s modes into its own page, and then take the section related to that mode of operation from the “how mitmproxy works” page and put it on that page.

5. Navigation

As features are added to mitmproxy(I think mitmweb is going to require a decent number of docs) the navigation of the documentation pages is going to become more unwieldy. Do we actually need to have every documentation page have it’s own line in the navigation? The Installing Certificates section, for example, could condense the navigation for these into 1-3 lines, rather than 9, in the navigation and then link to installing the cert for each OS off of one of those pages.

6. Tutorials vs Features vs Examples

I think a lot of the things that are listed as “Features” could be subsumed by the previously mentioned “command line options” page. Some of these features have tutorials associated with them and I suggest we split them out and link to them from the related command line option, as well as them being in the navigation. I think the briefer we can be on the theory behind a feature, focusing on not repeating ourselves, and having more examples the better off we will be.

7. Tutorials focusing on the means not the end

Perhaps we should focus the tutorials on what it is you are actually doing rather than the result. For example, the “Setting highscores on Apple's GameCenter” tutorial is a fun way to demonstrate replaying a request, but I don’t know that before I click on and read through the page. Perhaps it would be better to have a tutorial page that is about “Replaying requests” and “here is an example(or examples) of how to do that”.

8. Countershape

Lastly I wanted to discuss Countershape(I know it is @cortesi’s baby :)). Using Countershape is a relatively simple and efficient way of generating good looking documentation, once it is set up. I feel like the set up part is a bit of an obstacle to new contributor’s, to wrap their minds around, and possibly even regular contributors, that may be preventing people from doing something that is already a maintenance task. I think the idea behind countershape is that you shouldn’t have to need to set it up in order to contribute documentation, but I find myself wanting to test just to be sure. Maybe I’m too type A.

I took a look around at how other Open Source projects do documentation I took a look at Sphinx. I think it is what the python docs are written in. Ultimately it is overkill for this project, and would be more complex to setup and “learn” as it has its own syntax.

I saw some suggestions about using LaTeX as it works well with version control, and could be used to generate HTML. Ultimately this is probably in the same category as sphinx.

I think the best potential alternative is to use Github markdown pages. They don’t look as nice, but they might be easier to contribute to. Maybe we have a working set of docs in master that is written in markdown and then each release we convert those working copies to Countershape. There is also MkDocs, which lets you convert markdown in a similar way that Countershape does HTML.

Maybe we just keep using Countershape and need to have a section of the documentation that helps people through the process of setting up Countershape and explaining how it works? ”How to document mitmproxy” or some such? Or maybe have a way for people to throw together a quick Word/Open Office doc and then give that to someone in the project who can convert it into something that is going to make sense to Countershape?

Conclusion

I'm going to start with the least controversial stuff sometime this weekend hopefully and also prioritize other issues that are open and tagged "docs" as many of them slot nicely into the "command line options page" for example. Let me know what you all think.

Thanks!
Jim