866190 - migrate python NSS content to MDN

Status: RESOLVED FIXED

(www.mozilla.org :: Pages & Content, defect, P3)

Description

[Jennifer Bertsch [:jbertsch]]

Move content from http://www.mozilla.org/projects/security/pki/python-nss/ to MDN per instructions below

From: "Eric Shepherd" <[e-mail]>
To: "Jennifer Bertsch" <[e-mail]>
Sent: Wednesday, April 10, 2013 10:59:13 AM
Subject: Re: moving mozilla.org python nss content to MDN?

Yes, I think making this content live under the NSS subtree on MDN is a great place for it to live.

You'd start by creating a page at https://developer.mozilla.org/en-US/docs/NSS/PythonNSS (or whatever) and place all the content under that hierarchy.

You can copy and paste the HTML from SVN into MDN articles; after that, it will almost certainly need some cleaning up to match our style, but that shouldn't be too difficult.

Comment 1

[Justin Crawford [:hoosteeno] [:jcrawford]]

Assigning to John Dennis per :jbertsch's instruction.

Comment 2

[Mike Alexis [:malexis]]

Hi John, 
I'm the program manager for Mozilla.org and just wanted to check in with you. Are you still able to work on this? We definitely need to make progress on this soon--ideally within the next week. Let me know if there is anything else needed to get started.

Comment 3

[John Dennis]

No, I have not had any time to work on this yet. Unfortunately it's very low on my priority stack. I haven't even had time to look into what is required, if it's just a matter of moving the files and leaving a redirect behind then by all means do so and just give me a heads up. Otherwise it will have to wait till I can get to it, sorry.

Comment 4

[Jennifer Bertsch [:jbertsch]]

Hi John-

I'm going to add this to open this task up for another developer the mozilla.org Kanban board to see if someone else can get to it sooner.

Thanks for your help,
Jen

Comment 5

[John Karahalis [:openjck]]

What about this automatically-generated API documentation?

http://www.mozilla.org/projects/security/pki/python-nss/doc/api/current/html/

Do we want to migrate this to MDN as well? This would take some time, given the very different features MDN provides as a general-purpose (as opposed to API-specific) documentation platform, and the amount of content.

Comment 6

[John Dennis]

If API documentation doesn't belong on MDN then where does API documentation belong? Clearly there has to be a place for documenting API's and one would think a site with the name "Developer" in it would be the place. We have to provide the API documentation, it's not optional. Plus I really don't understand what this migration means, are you reformatting the files or just moving them? I had assumed it was just a matter of moving the files to a different location, if so then I'm not sure what the issue is. Each time we make a new release I regenerate the API doc and just upload it. Is that somehow going to be different if the doc is located on MDN?

Comment 7

[John Dennis]

Can someone give me a pointer to the MDN content guidelines, procedures, etc.?

Comment 8

[John Karahalis [:openjck]]

> If API documentation doesn't belong on MDN then where does API documentation
> belong? Clearly there has to be a place for documenting API's and one would
> think a site with the name "Developer" in it would be the place. We have to
> provide the API documentation, it's not optional.

We all seem to agree that the documentation should be moved to MDN. My point is that the move may be non-trivial.

> Plus I really don't understand what this migration means, are you reformatting
> the files or just moving them? I had assumed it was just a matter of moving the
> files to a different location, if so then I'm not sure what the issue is. Each
> time we make a new release I regenerate the API doc and just upload it. Is that
> somehow going to be different if the doc is located on MDN?

This may be where things get tricky. To my knowledge, MDN does not currently host any other self-contained documentation directories like this one. All articles are wiki pages written by hand.

That's not to say MDN can't support your existing workflow, it just doesn't right now. I think we all realize how important this documentation is and all want to find the right home for it. We just may need to think about how best to do that.

Copying Sheppy (MDN content lead) for his thoughts.

Comment 9

[Chris More [:cmore]]

Can we get IT to pull apache log files for the main directory to get an idea of pageviews per day/week/month? It would be nice to know how many eyeballs are on this content and then decide how much effort we want to put into this.

Comment 10

[Jennifer Bertsch [:jbertsch]]

Hi John and Kathleen-

To review, we are migrating content from the old php mozilla.org platform to the new python mozilla.org platform, and moving some of the content to non-mozilla.org locations, such as moving developer documentation to MDN and historical documents to the Mozilla wiki.

It appears to me that the content here is developer documentation.  Who is the audience?  Who is this content maintained for?

Thanks so much,
Jen

Comment 11

[Justin Crawford [:hoosteeno] [:jcrawford]]

I agree that this content will not easily migrate to MDN, simply because of its complexity, even though MDN would seem to be an appropriate destination for it. 

May I ask whether readthedocs.org would be an acceptable home for this content? We host lots of documentation there for projects we've built[0]. It hosts a standard documentation format[1] and displays it in a pleasing way. It is currently maintained by a Mozillian (Wraithan)[2]. It can be installed and run in-house if that ever becomes essential.[3] And it can easily fit into an automated publishing workflow.[4]

If so, a one-time modification of the publishing process would seem to be the next step, no?

[0] https://readthedocs.org/projects/playdoh/, https://readthedocs.org/projects/popcorn-maker/, https://readthedocs.org/projects/minion/, and many others
[1] http://sphinx-doc.org/
[2] https://github.com/rtfd/readthedocs.org/commits/master
[3] https://read-the-docs.readthedocs.org/en/latest/custom_installs/index.html
[4] http://read-the-docs.readthedocs.org/en/latest/webhooks.html

Comment 12

[John Karahalis [:openjck]]

We are actually working on pulling Read The Docs documentation into MDN (see bug 861981) so if this works out it could potentially be a path into the (fitting, it seems we agree) MDN brand.

Comment 13

[Kathleen Wilson]

(In reply to John Karahalis [:openjck] from comment #12)
> We are actually working on pulling Read The Docs documentation into MDN (see
> bug 861981) so if this works out it could potentially be a path into the
> (fitting, it seems we agree) MDN brand.

That sounds good.  

Should this bug be made dependent on bug #861981 ?

Comment 14

[Justin Crawford [:hoosteeno] [:jcrawford]]

I don't think it needs to be dependent -- the point is that we can put this content into readthedocs and eventually it will be possible to host that same format in MDN. But meanwhile we can solve the issue that NSS content needs to be migrated by moving this content.

Comment 15

[Kathleen Wilson]

I see, so the python-nss api documentation can be moved to readthedocs, and only the index.html content would need to be moved into developer.mozilla.org (MDN), and the MDN page would simply link to the appropriate location in readthedocs. Correct?

Comment 16

[Justin Crawford [:hoosteeno] [:jcrawford]]

That sounds great. So the plan proposed is...

* Move this page's content to MDN: http://www.mozilla.org/projects/security/pki/python-nss/, and we'd 
* Link there from here: https://developer.mozilla.org/en-US/docs/NSS
* Output the API docs (http://www.mozilla.org/projects/security/pki/python-nss/doc/api/current/html/index.html) in a format that can be hosted at readthedocs.org

The last step will take some developer analysis and coding. :openjck, does it sound like something you could tackle?

Comment 17

[John Karahalis [:openjck]]

Sounds good. I can work with John to research that last piece.

Comment 18

[Jennifer Bertsch [:jbertsch]]

Thanks everyone!

Comment 19

[John Karahalis [:openjck]]

My time is becoming more and more limited, unfortunately. Would anyone have bandwidth to take this from me?

Comment 20

[Justin Crawford [:hoosteeno] [:jcrawford]]

We've described one way forward for these docs -- a good way, I think. But we're having trouble finding someone who will undertake the migration proposed. Nevertheless, the NSS docs can't keep living on www.mozilla.org. 

What would happen if these docs went offline?

Comment 21

[John Dennis]

I don't have any problem with moving the API doc to readthedocs.org, it's fine with me.

I haven't tracked what happened with migrating the other doc to wiki format, is that done?

Comment 22

[Kathleen Wilson]

(In reply to John Dennis from comment #21) 
> I haven't tracked what happened with migrating the other doc to wiki format,
> is that done?

Yes. 

https://developer.mozilla.org/en-US/docs/PKI
https://developer.mozilla.org/en-US/docs/NSS
https://developer.mozilla.org/en-US/docs/JSS

Comment 23

[John Dennis]

re comment #22, sorry I wasn't clear, I meant the non-API portion of the python-nss doc, not the other NSS doc. jkarahalis said he was going to do it, but I guess that didnt' happen.

The doc is only one page, couldn't be too involved to translate to wiki format. I could do it but if it's already been done I don't want to waste time doing it twice.

Comment 24

[Justin Crawford [:hoosteeno] [:jcrawford]]

John, it'll be straightforward to move the non-API portion of the python-nss doc[0], and I think I can find someone to do it. The sticking point is the API portion[1], since a manual migration seems out of the question. It'll likely need someone to code a migration. 
* In comment 21, are you volunteering to code that migration? 
* When can you do it? 
* If we move the non-API document to MDN soon, can the link from the non-API document to the API docs be broken until the API docs are online again?

[0]http://www.mozilla.org/projects/security/pki/python-nss/
[1]http://www.mozilla.org/projects/security/pki/python-nss/doc/api/current/html/index.html

Comment 25

[Jennifer Bertsch [:jbertsch]]

Steven's team will look to determine scope (2 days vs 10 weeks) and make a recommendation for how to proceed.

Comment 26

[Steven Garrity [:sgarrity]]

(In reply to Jennifer Bertsch [:jbertsch] from comment #25)
> Steven's team will look to determine scope (2 days vs 10 weeks) and make a
> recommendation for how to proceed.

We ran into the same issues that John did in trying to use ReadTheDocs for the API docs. In the "2 hours or 2 weeks" question, it's definitely more than 2hrs.

As for the non-API docs, I have ported the http://mozilla.org/projects/security/pki/python-nss/ page to MDN [1] and created a pull request to add a redirect: https://github.com/mozilla/bedrock/pull/1776

The API docs remain, and we'll need jdennis to give feedback on where that should go.

[1] https://developer.mozilla.org/en-US/docs/Python_binding_for_NSS

Comment 27

[[github robot]]

Commits pushed to master at https://github.com/mozilla/bedrock

https://github.com/mozilla/bedrock/commit/f94743f23aff93b41c703b1e7e830f2ed9f0349c
Redirect python-nss page to MDN (Bug 866190)

https://github.com/mozilla/bedrock/commit/9c6189556a49a62d9c8dc42f9c23201c6374308b
Merge pull request #1776 from sgarrity/bug-866190-python-nss-redirect

Redirect python-nss page to MDN (Bug 866190)

Comment 28

[raymond [:retornam] (inactive)]

fixed on stage
www.allizom.org/projects/security/pki/python-nss/ ---->

https://developer.mozilla.org/en-US/docs/Python_binding_for_NSS

Comment 29

[raymond [:retornam] (inactive)]

verified fixed


mozilla.org/projects/security/pki/python-nss/  ---->
https://developer.mozilla.org/en-US/docs/Python_binding_for_NSS

Comment 30

[Justin Crawford [:hoosteeno] [:jcrawford]]

The new content on MDN is great!

The API docs (the third bullet in comment 16) are still outstanding. Reopening this bug until we've found a new home for them.

Comment 31

[Steven Garrity [:sgarrity]]

Attachment: Patch to remove python-nss page

Now that the python-nss page is moved to MDN, here's a patch to remove the HTML file from mozilla.org SVN.

Note that this is just the overview page, not the API docs.

Comment 32

[Steven Garrity [:sgarrity]]

The projects/security/pki/python-nss/index.html file has been removed from SVN (r125482 in branches/staging and trunk in r125485).

Comment 33

[Steven Garrity [:sgarrity]]

Now that Bug 975476 is done (though we moved the content to to our website-archive site rather than readthedocs), I think all of the Python NSS content has been ported out of SVN.