Re: Call for editors and proofreaders of the team book
> Hi Gavin,
Hi!
> > I used write stuff for Fedora magazine, Fedora docs, part of the
> > OpenLDAP docs team, Amanda, a bit of Asterisk way back and am just
> > about finished my book for pragprog.com on migrating a C project to
> > Rust - a LOT of FFI.
>
> That seems to be a _lot_ of technical writing experience! Could you
> give some pointers? You see, As a Debianite, I'm not always familiar
> with Fedora or other "outside" projects ;)
The Fedora stuff was a long time ago :-D
If it was me writing the book, based on the PragProg internal author
guide (I'll grab some more from this guide later for us), the key is
to pick the reader level but cater for the expert too where possible:
* What are we expecting them to already understand?
* Can we direct them to those places to help them up skill?
* Do we have any full tutorial based chapters?
* What is the lifecycle of a package?
* Where do they go for help?
* What level do we want to get them too?
* What's the core theme of the book/guide?
* What can they do after reading it that they couldn't do before?
* ....
I feel like we're missing a few things between section 2 & 3 here:
https://rust-team.pages.debian.net/book/
For me, I used all the docs in the repo and the internet, but if there
was a "Packing XXX project for Debian" tutorial that is something like
this:
1. Packing a Rust binary project
- Covers a normal Debian package, then the Rust bits
2. Packing the Rust libs for that project
- This could be part of the tutorial or something that you can go
straight to. My own experience is a normal C binary package via
autotools which needs Rust libs, which takes me to this section of the
book.
Then the current 3-6 sections at
https://rust-team.pages.debian.net/book/ are nice bits to read after
the tut or deeper details. The end result is that we take the reader
through the example scenerio, we hand hold that process, we show how
to lint it, validate it etc. which then allows them to apply the
examples to their own project.
We then need "A Day in the life of a Debian Rust lib maintainer" to
cover what everyone does after the first release.
Even if this is all for your future self to read later :-D
> > The book takes a lot of my time, so maybe proofreading for starters.
> > I'll be finished in a few months though, so will have more time then.
>
> Sure, all forms of contribution are appreciated. Take your time ;)
Thanks!
> > Beginner packaging skills at the moment, but learning more whilst I
> > package SentryPeer and its Rust deps. That work is on hold right now
> > due to work and the book.
>
> The book you talked about above seems to be pretty in depth for Rust.
> That's obviously good, especially since the DRT kinda lacks in FFI
> experience (cdylibs, interop, etc). It's only a matter of time before
> you get to know Debian packaging.
Yep, it's all starting to fall into place.
> Thanks again, and looking forward to working with you ;)
Likewise!
--
Kind Regards,
Gavin Henry.
https://sentrypeer.org
Reply to: