[panda-users] documentation rearrangements

[Manolis Stamatogiannakis]

Hi all,

I noticed there's plenty of activity reorganizing the PANDA documentation.
While this was much needed and is definitely welcome, I'd like to express a
few concerns related to the ongoing reorganization.

Monolithic manual. I hope this is only temporary and we'll have split files
at the end of the reorganization. I find having the manual as a single
markdown file very unwieldy and impractical. You won't ever need *all* the
information at the same time. With 2k lines to scroll through, finding what
you want becomes very difficult.

Removing compile.md. I don't understand why this part of documentation was
killed. This makes it more difficult to install PANDA on anything else than
Debian/Ubuntu. It was much easier to go through compile.md and adapt each
step to your OS than reading and adapting the bash script.
Moreover, it seems the bash script has currently been tested only for
Debian 7. E.g. llvm-3.3 is not available for Debian 8. So now you have to
go google how to install it, something that was already documented.
Plus, many first-time users may not be comfortable running a script that
they haven't carefully examined and alters their system.

Documentation namespacing - or lack thereof. The current restructuring
seems like a good opportunity to use some sort of namespacing for the
documentation. E.g. rename stuff related to PANDA core to panda_*.md,
plugin related stuff to plugin_*.md, use cases (e.g. dynamic slicing) to
usecase_*.md. This doesn't seem to be planned for now.

I'm willing to contribute towards addressing these concerns if there is a
consensus for any of them.

Cute logo btw. Sign me up when you order for PANDA tshirts :)

Best regards,
Manolis
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mailman.mit.edu/pipermail/panda-users/attachments/20160123/981b1e1b/attachment.html