1184125 - MDN Docs are still too technical (according to new Mozilla contributors who spoke recently to me). Need Revisions made to explain some content in a more basic way for newbies.

Status: RESOLVED INVALID

(Developer Documentation Graveyard :: MDN Meta Docs, defect)

Description

[April Morone]

Attachment: 2015-07-15-093726_1024x768_scrot.png Sai Karthik gave me permissions to take a screenshot of his IM to me of that to add, here, of his opinion about MDN being not for newbies.

MDN Docs are still too technical (according to new Mozilla contributors, including Sai Karthik, who spoke recently to me). Need Revisions made to explain some content in a more basic way for newbies.

Sai Karthik told me in a Facebook IM of that he thinks MDN is for experienced, but he is a newbie.  He doesn't understand the info on MDN about porting Firefox OS.  He thinks that info, too, is too technical and isn't for newbies.  He has allowed me to take a screenshot of some of what he told me in that IM to share, here.

I am aware of that some technical processes can only be explained to a certain level of explanation.  But, if someone could try to revise this to make it more basic of explanation about porting (and of other info on MDN), that might help newbies, more.

Comment 1

[Jeremie Patonnier :Jeremie]

Hi!

Thanks for reporting this :)

Would it be possible to be a bit more specific about what is too complexe on MDN? For what I understand it seams that the issue is about porting Firefox OS on Android. I agree that the current documentation about that specific topic assume a lot of engineering prerequisite, but porting any kind of thing onto Android requires to be quite comfortable with many computer skills. In the case of Firefox OS, it's highly discourage to get into such porting if you've never done this before with some alternative Android build. This is not a trivial task (so far, I heard about plan to lower this down).

In a more general approach, the MDN writing team is quite aware of the general complexity of some MDN content. That's why we have start a new project to make MDN more beginner friendly. This is the Learning Area project:

https://developer.mozilla.org/en-US/docs/MDN/Plans/Learning

This is a long way to go, and we first want to focus on Web Standard technologies. However, any help is welcome to help making MDN easier for beginners and I'll be glad to help anyone who want to get involved with this :)

Comment 2

[April Morone]

(In reply to Jeremie Patonnier :Jeremie from comment #1)
> Hi!
> 
> Thanks for reporting this :)
> 
> Would it be possible to be a bit more specific about what is too complexe on
> MDN? For what I understand it seams that the issue is about porting Firefox
> OS on Android. I agree that the current documentation about that specific
> topic assume a lot of engineering prerequisite, but porting any kind of
> thing onto Android requires to be quite comfortable with many computer
> skills. In the case of Firefox OS, it's highly discourage to get into such
> porting if you've never done this before with some alternative Android
> build. This is not a trivial task (so far, I heard about plan to lower this
> down).
> 
> In a more general approach, the MDN writing team is quite aware of the
> general complexity of some MDN content. That's why we have start a new
> project to make MDN more beginner friendly. This is the Learning Area
> project:
> 
> https://developer.mozilla.org/en-US/docs/MDN/Plans/Learning
> 
> This is a long way to go, and we first want to focus on Web Standard
> technologies. However, any help is welcome to help making MDN easier for
> beginners and I'll be glad to help anyone who want to get involved with this
> :)

Sure.  Sai Karthik is an extreme beginner who had wanted to build Firefox OS on a type of phone that wasn't on the list of phones MDN shows Firefox OS can be built on.  So, he was told he could try helping port it.  But, he then told me that, on top of not having a high enough internet to do this and no admin rights to server, he feels that the documentation of porting MDN provides isn't for newbies, but is for experienced.  I want to help him, but with my schedule and health problems, combined, I cannot on top of testing Firefox OS, testing my apps, and soon doing app reviewing, too, plus rebuilding my own previous website, and then getting info together for teaching some, on the side as I can.

Web Standard technologies, ... I understand.  :)  I would like to help in make MDN easier, but I worry I won't have enough time to do so.  I can try.

Comment 3

[Eric Shepherd [:sheppy]]

I don't think this is really a "bug". The subject matter at question is inherently crazy technical. If there are areas for improvement, we need to get more specific bugs filed. I'm closing this for now; please take discussion to the dev-mdc list and then file bugs about specific issues that may be legitimate.