[panda-users] documentation rearrangements

[Brendan Dolan-Gavitt]

Hi Manolis,

Sorry it's taken a while to get back to you. The semester just started
here and I haven't had a lot of time.

[Tim, Patrick – please chime in since you guys also worked on the
documentation reorganization.]

I think I agree that a monolithic manual is difficult to navigate,
particularly within GitHub or in a text editor, and some things --
like the callback reference -- definitely don't belong in the main
document. I do like the fact that its current incarnation can be
rendered as a nice PDF for printing out a reference, but we could
probably salvage that by periodically generating a pdf manual by
combining smaller bits of documentation and linking it somewhere. I do
think we will still need some kind of master index into the
documentation that tells people where to find each topic.

For compile.md – I think our reasoning for axing this was that most of
us don't use it, and pieces of it were starting to get out of date and
broken (for example, I believe it was compiling LLVM with gcc-4.9 but
then PANDA with the system default gcc, which causes ABI issues when
the system gcc is version 5). I'm not sure what the best way forward
here is, unless we commit to actually supporting different
distributions. One small note is that the instructions on compiling
LLVM are still there:

https://github.com/moyix/panda/blob/master/docs/manual.md#building-llvm

...but the fact that you couldn't find them probably speaks to your
point that the manual is too big at present.

Namespacing – good idea. As we've added more documentation it has
gotten kind of messy in there. I think either prefixes like you're
suggesting or subdirectories would be a good solution.

So, to move forward, it seems like we should (assuming others agree on
splitting things up):

1. Figure out what the reasonable chunks to split the manual into are,
and generate a table of contents / index.
2. Find a way to still generate a nice PDF for printing (probably can
be done with pandoc somehow...)
3. Figure out what the categories are – e.g. in addition to panda_,
plugin_, and usecase_, do we also need tutorial_ ?

Best,
Brendan

PS: We will let you know about t-shirts :) I know Tim has already been
pricing out PANDA coffee mugs...

On Sat, Jan 23, 2016 at 7:42 PM, Manolis Stamatogiannakis
<mstamat at gmail.com> wrote:
> 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
>
> _______________________________________________
> panda-users mailing list
> panda-users at mit.edu
> http://mailman.mit.edu/mailman/listinfo/panda-users
>